<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
    <head>
        <title>CruiseControl.NET : NAnt Task</title>
	    <link rel="stylesheet" href="styles/site.css" type="text/css" />
        <META http-equiv="Content-Type" content="text/html; charset=UTF-8">	    
    </head>

    <body>
	    <table class="pagecontent" border="0" cellpadding="0" cellspacing="0" width="100%" bgcolor="#ffffff">
		    <tr>
			    <td valign="top" class="pagebody">
				    <div class="pageheader">
					    <span class="pagetitle">
                            CruiseControl.NET : NAnt Task
                                                    </span>
				    </div>
				    <div class="pagesubheading">
					    This page last changed on Jul 07, 2009 by <font color="#0050B2">dna</font>.
				    </div>

				    <h3><a name="NAntTask-Examples"></a>Examples</h3>

<p>Minimalist Example:</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-xml"><span class="code-tag">&lt;nant /&gt;</span></pre>
</div></div>
<p>Full example:</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-xml"><span class="code-tag">&lt;nant&gt;</span>
  <span class="code-tag">&lt;executable&gt;</span>c:\fromcvs\myrepo\myproject\tools\nant\nant.exe<span class="code-tag">&lt;/executable&gt;</span>
  <span class="code-tag">&lt;baseDirectory&gt;</span>c:\fromcvs\myrepo\myproject<span class="code-tag">&lt;/baseDirectory&gt;</span>
  <span class="code-tag">&lt;buildArgs&gt;</span>-D:cvs.executable=c:\putty\cvswithplinkrsh.bat<span class="code-tag">&lt;/buildArgs&gt;</span>
  <span class="code-tag">&lt;nologo&gt;</span>false<span class="code-tag">&lt;/nologo&gt;</span>
  <span class="code-tag">&lt;buildFile&gt;</span>cruise.build<span class="code-tag">&lt;/buildFile&gt;</span>
  <span class="code-tag">&lt;logger&gt;</span>My.Other.XmlLogger<span class="code-tag">&lt;/logger&gt;</span>
  <span class="code-tag">&lt;targetList&gt;</span>
    <span class="code-tag">&lt;target&gt;</span>run<span class="code-tag">&lt;/target&gt;</span>
  <span class="code-tag">&lt;/targetList&gt;</span>
  <span class="code-tag">&lt;buildTimeoutSeconds&gt;</span>1200<span class="code-tag">&lt;/buildTimeoutSeconds&gt;</span>
<span class="code-tag">&lt;/nant&gt;</span></pre>
</div></div>

<h3><a name="NAntTask-ConfigurationElements%3A"></a>Configuration Elements:</h3>

<table class='confluenceTable'><tbody>
<tr>
<th class='confluenceTh'> Node </th>
<th class='confluenceTh'> Description </th>
<th class='confluenceTh'> Type </th>
<th class='confluenceTh'> Required </th>
<th class='confluenceTh'> Default </th>
<th class='confluenceTh'> Version </th>
</tr>
<tr>
<td class='confluenceTd'> executable </td>
<td class='confluenceTd'> The path of the version of nant.exe you want to run. If this is relative, then must be relative to either (a) the base directory, (b) the CCNet Server application, or (c) if the path doesn't contain any directory details then can be available in the system or application's 'path' environment variable </td>
<td class='confluenceTd'> string </td>
<td class='confluenceTd'> false </td>
<td class='confluenceTd'> <tt>nant.exe</tt> </td>
<td class='confluenceTd'>&nbsp;</td>
</tr>
<tr>
<td class='confluenceTd'> baseDirectory </td>
<td class='confluenceTd'> The directory to run the NAnt process in. If relative, is a subdirectory of the <a href="Project Configuration Block.html#ProjectConfigurationBlock-workingDirectory">Project Working Directory</a> </td>
<td class='confluenceTd'> string </td>
<td class='confluenceTd'> false </td>
<td class='confluenceTd'> <a href="Project Configuration Block.html#ProjectConfigurationBlock-workingDirectory">Project Working Directory</a> </td>
<td class='confluenceTd'>&nbsp;</td>
</tr>
<tr>
<td class='confluenceTd'> buildFile </td>
<td class='confluenceTd'> The name of the build file to run, relative to the baseDirectory. </td>
<td class='confluenceTd'> string </td>
<td class='confluenceTd'> false </td>
<td class='confluenceTd'> no build file specified (NAnt will use the default build file in the working directory) </td>
<td class='confluenceTd'>&nbsp;</td>
</tr>
<tr>
<td class='confluenceTd'> buildArgs </td>
<td class='confluenceTd'> Any arguments to pass through to NAnt (e.g to specify build properties) </td>
<td class='confluenceTd'> string </td>
<td class='confluenceTd'> false </td>
<td class='confluenceTd'> no args specified </td>
<td class='confluenceTd'>&nbsp;</td>
</tr>
<tr>
<td class='confluenceTd'> nologo </td>
<td class='confluenceTd'> Whether to use the <tt>&#45;nologo</tt> argument when calling NAnt </td>
<td class='confluenceTd'> boolean </td>
<td class='confluenceTd'> false </td>
<td class='confluenceTd'> true </td>
<td class='confluenceTd'>&nbsp;</td>
</tr>
<tr>
<td class='confluenceTd'> logger </td>
<td class='confluenceTd'> The NAnt logger to use. If you are using a version of NAnt prior to 0.8.3, you may need to specify this as SourceForge.NAnt.XmlLogger. </td>
<td class='confluenceTd'> string </td>
<td class='confluenceTd'> false </td>
<td class='confluenceTd'> NAnt.Core.XmlLogger </td>
<td class='confluenceTd'>&nbsp;</td>
</tr>
<tr>
<td class='confluenceTd'> listener </td>
<td class='confluenceTd'> The NAnt listener to use. </td>
<td class='confluenceTd'> string </td>
<td class='confluenceTd'> false </td>
<td class='confluenceTd'> NAnt.Core.DefaultLogger </td>
<td class='confluenceTd'> 1.5.0 </td>
</tr>
<tr>
<td class='confluenceTd'> buildTimeoutSeconds </td>
<td class='confluenceTd'> Number of seconds to wait before assuming that the process has hung and should be killed. </td>
<td class='confluenceTd'> int </td>
<td class='confluenceTd'> false </td>
<td class='confluenceTd'> 600 (10 minutes) </td>
<td class='confluenceTd'>&nbsp;</td>
</tr>
<tr>
<td class='confluenceTd'> targetList </td>
<td class='confluenceTd'> A list of targets to be called. CruiseControl.NET does not call NAnt once for each target, it uses the NAnt feature of being able to specify multiple targets. </td>
<td class='confluenceTd'> string list </td>
<td class='confluenceTd'> false </td>
<td class='confluenceTd'> no targets specified (NAnt will use the build's default target </td>
<td class='confluenceTd'>&nbsp;</td>
</tr>
<tr>
<td class='confluenceTd'> description </td>
<td class='confluenceTd'> If filled in, this will be shown in the buildstage as the process name <br clear="all" /> </td>
<td class='confluenceTd'> string <br clear="all" /> </td>
<td class='confluenceTd'> false <br clear="all" /> </td>
<td class='confluenceTd'> n/a </td>
<td class='confluenceTd'>&nbsp;</td>
</tr>
<tr>
<td class='confluenceTd'> dynamicValues </td>
<td class='confluenceTd'> Any dynamic parameters to be used. See <a href="Dynamic Parameters.html" title="Dynamic Parameters">Dynamic Parameters</a> </td>
<td class='confluenceTd'> Dynamic values array - see <a href="Dynamic Parameters.html" title="Dynamic Parameters">Dynamic Parameters</a> </td>
<td class='confluenceTd'> No </td>
<td class='confluenceTd'> <em>None</em> </td>
<td class='confluenceTd'> 1.5.0 </td>
</tr>
</tbody></table>

<h3><a name="NAntTask-NAntoutputinXml"></a>NAnt output in Xml</h3>

<p>CruiseControl.NET expects NAnt to generate its output as Xml so that the build results can be parsed and rendered appropriately.  To accomplish this, CruiseControl.NET will, by default, launch NAnt using the "<b>&#45;logger:NAnt.Core.XmlLogger</b>" argument.  If you want to override this behaviour, specify the <b>logger</b> property in the NAntBuilder configuration in the <b>ccnet.config</b> file.  If this element is specified but is empty then NAnt will be started with the default logger (though this may cause some problems for CCNet).  It is also possible to instruct NAnt to log its output to an Xml file and then merge the file into the build using the <a href="File Merge Task.html" title="File Merge Task">File Merge Task</a>.</p>

<p><img class="emoticon" src="images/icons/emoticons/warning.gif" height="16" width="16" align="absmiddle" alt="" border="0"/> NOTE: the configuration of which NAnt logger to use was orginally specified in the <b>ccnet.exe.config</b> file.  This has now been deprecated, and the "NAnt.Logger" element in the &lt;appSettings&gt; section can now be removed.</p>

<h3><a name="NAntTask-NUnitandNAnt"></a>NUnit and NAnt</h3>

<p>CruiseControl.NET uses xsl to process the build log and produce html for display on the web page. Since xml is so easy to parse the nunit2 task in NAnt can produce xml output. The tasks must be configured to do that in order for test results to show up on the web page. Typically this is done by adding a formatter element to the nunit2 task and setting the type to be "Xml". Additionally the usefile flag of the formatter element must be set to "false". If it isn't the nunit2 task will try and save the output to a file and not write it out to the build log.</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-xml"><span class="code-tag">&lt;target name=<span class="code-quote">"test.unit"</span> depends=<span class="code-quote">"compile"</span> description=<span class="code-quote">"runs unit tests"</span>&gt;</span>
	<span class="code-tag">&lt;nunit2&gt;</span>
		<span class="code-tag">&lt;formatter type=<span class="code-quote">"Xml"</span> usefile=<span class="code-quote">"false"</span>/&gt;</span>
		<span class="code-tag">&lt;test assemblyname=<span class="code-quote">"${build.dir}\${core.dll}"</span> fork=<span class="code-quote">"true"</span>/&gt;</span>
		<span class="code-tag">&lt;test assemblyname=<span class="code-quote">"${build.dir}\${console.exe}"</span> fork=<span class="code-quote">"true"</span>/&gt;</span>
	<span class="code-tag">&lt;/nunit2&gt;</span>
<span class="code-tag">&lt;/target&gt;</span></pre>
</div></div>
<p>It would be pretty tedious for developers to read the xml output when they run the build locally. Define a property for the build output type and set it to "Plain" and use the property in the formatter element..</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-xml"><span class="code-tag">&lt;property name=<span class="code-quote">"outputType"</span> value=<span class="code-quote">"Plain"</span>/&gt;</span>
	...
	<span class="code-tag">&lt;formatter type=<span class="code-quote">"${outputType}"</span> usefile=<span class="code-quote">"false"</span>/&gt;</span>
	...</pre>
</div></div>
<p>Then in the ccnet.config file pass in a different value for outputType.</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-xml"><span class="code-tag">&lt;nant&gt;</span>
	...
	<span class="code-tag">&lt;buildArgs&gt;</span><span class="code-quote">"-DoutputType=Xml"</span><span class="code-tag">&lt;/buildArgs&gt;</span>
	...
<span class="code-tag">&lt;/nant&gt;</span></pre>
</div></div>

<h3><a name="NAntTask-AccessingCruiseControl.NETbuildlabelsinNAnt"></a>Accessing CruiseControl.NET build labels in NAnt</h3>

<p>CCNet will pass the current build label to NAnt via the NAnt property <tt>CCNetLabel</tt>.  This means that you can access use this property to, for example, archive the newly built assemblies in a folder with the same name as the build label (this is what we do on <a href="http://ccnetlive.thoughtworks.com/CCNet-builds/">CCNetLive </a>.  Here's some example NAnt script demonstrating how to do this:</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-xml"><span class="code-tag">&lt;target name=<span class="code-quote">"dist.publish"</span> depends=<span class="code-quote">"dist"</span>&gt;</span>
	<span class="code-tag">&lt;ifnot propertyexists=<span class="code-quote">"CCNetLabel"</span>&gt;</span>
		<span class="code-tag">&lt;fail message=<span class="code-quote">"CCNetLabel property not set, so can't create labelled distribution files"</span> /&gt;</span>
	<span class="code-tag">&lt;/ifnot&gt;</span>
	<span class="code-tag">&lt;property name=<span class="code-quote">"publish.dir"</span> value=<span class="code-quote">"D:\download-area\CCNet-Builds\${CCNetLabel}"</span> /&gt;</span>

	<span class="code-tag">&lt;mkdir dir=<span class="code-quote">"${publish.dir}"</span> /&gt;</span>
	<span class="code-tag">&lt;copy todir=<span class="code-quote">"${publish.dir}"</span>&gt;</span>
		<span class="code-tag">&lt;fileset basedir=<span class="code-quote">"dist"</span>&gt;</span>
			<span class="code-tag">&lt;includes name=<span class="code-quote">"*"</span>/&gt;</span>
		<span class="code-tag">&lt;/fileset&gt;</span>
	<span class="code-tag">&lt;/copy&gt;</span>
<span class="code-tag">&lt;/target&gt;</span></pre>
</div></div>

<h3><a name="NAntTask-IntegrationProperties"></a>Integration Properties</h3>

<p>The following parameters are passed to NAnt as command-line arguments:</p>
<table class='confluenceTable'><tbody>
<tr>
<th class='confluenceTh'> Label </th>
<th class='confluenceTh'> Description </th>
<th class='confluenceTh'> Example </th>
<th class='confluenceTh'> Version </th>
</tr>
<tr>
<td class='confluenceTd'> CCNetBuildCondition </td>
<td class='confluenceTd'> The condition used to trigger the build, indicating if the build was triggered by new modifications or if it was forced.  Legal values are: "IfModificationExists" or "ForceBuild" </td>
<td class='confluenceTd'> ForceBuild </td>
<td class='confluenceTd'>&nbsp;</td>
</tr>
<tr>
<td class='confluenceTd'> CCNetIntegrationStatus </td>
<td class='confluenceTd'> The status of the current integration. Could be Success, Failure, Exception or Unknown </td>
<td class='confluenceTd'> Success </td>
<td class='confluenceTd'>&nbsp;</td>
</tr>
<tr>
<td class='confluenceTd'> CCNetLabel </td>
<td class='confluenceTd'> The label used to identify the CCNet build.  This label is generated by the CCNet labeller. </td>
<td class='confluenceTd'> 1.0.2.120 </td>
<td class='confluenceTd'>&nbsp;</td>
</tr>
<tr>
<td class='confluenceTd'> CCNetLastIntegrationStatus </td>
<td class='confluenceTd'> The status of the previous integration. Could be Success, Failure, Exception or Unknown </td>
<td class='confluenceTd'> Success </td>
<td class='confluenceTd'>&nbsp;</td>
</tr>
<tr>
<td class='confluenceTd'> CCNetProject </td>
<td class='confluenceTd'> The name of the CCNet project that is being integrated. </td>
<td class='confluenceTd'> MyProject </td>
<td class='confluenceTd'>&nbsp;</td>
</tr>
<tr>
<td class='confluenceTd'> CCNetBuildDate </td>
<td class='confluenceTd'> The date of the build (in yyyy-MM-dd format) </td>
<td class='confluenceTd'> 2005-08-10 </td>
<td class='confluenceTd'>&nbsp;</td>
</tr>
<tr>
<td class='confluenceTd'> CCNetBuildTime </td>
<td class='confluenceTd'> The time of the start of the build (in HH:mm:ss format) </td>
<td class='confluenceTd'> 08:45:12 </td>
<td class='confluenceTd'>&nbsp;</td>
</tr>
<tr>
<td class='confluenceTd'> CCNetArtifactDirectory </td>
<td class='confluenceTd'> The <a href="Project Configuration Block.html#ProjectConfigurationBlock-artifactDirectory">project artifact directory</a> (as an absolute path) </td>
<td class='confluenceTd'> <tt>c:\program files\CruiseControl.NET\Server\MyProject\Artifacts</tt> </td>
<td class='confluenceTd'>&nbsp;</td>
</tr>
<tr>
<td class='confluenceTd'> CCNetWorkingDirectory </td>
<td class='confluenceTd'> The <a href="Project Configuration Block.html#ProjectConfigurationBlock-workingDirectory">project working directory</a> (as an absolute path) </td>
<td class='confluenceTd'> <tt>c:\program files\CruiseControl.NET\Server\MyProject\WorkingDirectory</tt> </td>
<td class='confluenceTd'>&nbsp;</td>
</tr>
<tr>
<td class='confluenceTd'> CCNetRequestSource </td>
<td class='confluenceTd'> The source of the integration request; this will generally be the name of the trigger that raised the request. </td>
<td class='confluenceTd'> IntervalTrigger </td>
<td class='confluenceTd'> 1.1.0 </td>
</tr>
<tr>
<td class='confluenceTd'> CCNetFailureUsers </td>
<td class='confluenceTd'> The list of users who have contributed modifications to a sequence of builds that has failed. </td>
<td class='confluenceTd'> John, Smith<br clear="all" /> </td>
<td class='confluenceTd'>&nbsp;</td>
</tr>
<tr>
<td class='confluenceTd'> CCNetListenerFile </td>
<td class='confluenceTd'> <a href="http://confluence.public.thoughtworks.org/display/CCNETCOMM/Viewing+build+progress+with+Nant+and+MSBuild">Viewing build progress with Nant and MSBuild</a> </td>
<td class='confluenceTd'> c:\Project\Artifact\listener.xml </td>
<td class='confluenceTd'> 1.4.0 </td>
</tr>
<tr>
<td class='confluenceTd'> CCNetProjectUrl </td>
<td class='confluenceTd'> The URL where the project is located </td>
<td class='confluenceTd'> <a href="http://myhost/ccnet/server/">http://myhost/ccnet/server/</a> </td>
<td class='confluenceTd'>&nbsp;</td>
</tr>
<tr>
<td class='confluenceTd'> CCNetNumericLabel </td>
<td class='confluenceTd'> Contains the label as an integer if conversion is possible, otherwise zero. </td>
<td class='confluenceTd'> 1 </td>
<td class='confluenceTd'>&nbsp;</td>
</tr>
<tr>
<td class='confluenceTd'> CCNetModifyingUsers <br clear="all" /> </td>
<td class='confluenceTd'> The list of users who have contributed to the current build only <br clear="all" /> </td>
<td class='confluenceTd'> Smith </td>
<td class='confluenceTd'>&nbsp;</td>
</tr>
<tr>
<td class='confluenceTd'> CCNetUser </td>
<td class='confluenceTd'> The user who forced the build. If security is off, or the build is not forced, then this will not be set. </td>
<td class='confluenceTd'> John Doe </td>
<td class='confluenceTd'> 1.5.0 </td>
</tr>
</tbody></table>

<h3><a name="NAntTask-Additionalinformation"></a>Additional information</h3>

<p>See <a href="Using CruiseControl.NET with NAnt.html" title="Using CruiseControl.NET with NAnt">Using CruiseControl.NET with NAnt</a> for more information on working with NAnt and CruiseControl.Net.</p>

				    
                    			    </td>
		    </tr>
	    </table>
	    <table border="0" cellpadding="0" cellspacing="0" width="100%">
			<tr>
				<td height="12" background="http://confluence.public.thoughtworks.org//images/border/border_bottom.gif"><img src="images/border/spacer.gif" width="1" height="1" border="0"/></td>
			</tr>
		    <tr>
			    <td align="center"><font color="grey">Document generated by Confluence on Sep 29, 2009 20:59</font></td>
		    </tr>
	    </table>
    </body>
</html>